<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Loop (parse a string) - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The Loop Parse statement retrieves substrings (fields) from a string, one at a time." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Loop (parse a string)</h1>

<p>Retrieves substrings (fields) from a string, one at a time.</p>

<pre class="Syntax"><span class="func">Loop, Parse</span>, InputVar <span class="optional">, Delimiters, OmitChars</span></pre>
<h2>Parameters</h2>
<dl>

  <dt>Parse</dt>
  <dd><p>This parameter must be the word PARSE, and unlike other loop types, it must not be a variable reference that resolves to the word PARSE.</p></dd>

  <dt>InputVar</dt>
  <dd>
    <p>The name of the variable whose contents will be analyzed. Do not enclose the name in percent signs unless you want the <em>contents</em> of the variable to be used as the name.</p>
    <p><span class="ver">[v1.1.21+]:</span> This parameter can be an <code>% <a href="../Variables.htm#Expressions">expression</a></code>, but the percent-space prefix must be used.</p>
  </dd>

  <dt>Delimiters</dt>
  <dd><p>If this parameter is blank or omitted, each character of <em>InputVar</em> will be treated as a separate substring.</p>
      <p>If this parameter is <strong>CSV</strong>, <em>InputVar</em> will be parsed in standard comma separated value format. Here is an example of a CSV line produced by MS Excel:</p>
<pre class="no-highlight">&quot;first field&quot;,SecondField,&quot;the word &quot;&quot;special&quot;&quot; is quoted literally&quot;,,&quot;last field, has literal comma&quot;</pre>
      <p>Otherwise, <em>Delimiters</em> contains one or more  characters (case sensitive), each of which is used to determine where the boundaries between substrings occur in <em>InputVar</em>.</p>
      <p>Delimiter characters are not considered to be part of the substrings themselves. In addition, if there is nothing between a pair of delimiters within <em>InputVar</em>, the corresponding substring will be empty.</p>
      <p>For example: <code>`,</code> (an escaped comma) would divide the string based on every occurrence of a comma. Similarly, %A_Tab%%A_Space% would start a new substring every time a space or tab is encountered in <em>InputVar</em>.</p>
      <p>To use a string as a delimiter rather than a character, first use <a href="StringReplace.htm">StringReplace</a> to replace all occurrences of the string with a single character that is never used literally in the text, e.g. one of these special characters: &cent;&curren;&yen;&brvbar;&sect;&copy;&ordf;&laquo;&reg;&micro;&para;. Consider this example, which uses the string &lt;br&gt; as a delimiter:</p>
      <pre>StringReplace, NewHTML, HTMLString, &lt;br&gt;, &cent;, All
Loop, parse, NewHTML, &cent; <em>; Parse the string based on the cent symbol.</em>
{
...
}</pre></dd>

  <dt>OmitChars</dt>
  <dd><p>An optional list of characters (case sensitive) to exclude from the beginning and end of each substring. For example, if <em>OmitChars</em> is %A_Space%%A_Tab%, spaces and tabs will be removed from the beginning and end (but not the middle) of every retrieved substring.</p>
    <p>If <em>Delimiters</em> is blank, <em>OmitChars</em> indicates which characters should be excluded from consideration (the loop will not see them).</p>
    <p>Unlike the last parameter of most other commands, commas in <em>OmitChars</em> must be escaped (`,).</p></dd>

</dl>

<h2>Remarks</h2>
<p>A string parsing loop is useful when you want to operate on each field contained in a string, one at a time. Parsing loops use less memory than <a href="StringSplit.htm">StringSplit</a> (since StringSplit creates a permanent <a href="../misc/Arrays.htm#pseudo">pseudo-array</a>) and in most cases they are easier to use.</p>
<p id="LoopField">The built-in variable <strong>A_LoopField</strong> exists within any parsing loop. It contains the contents of the current substring (field) from <em>InputVar</em>. If an inner parsing loop is enclosed by an outer parsing loop, the innermost loop's field will take precedence.</p>
<p>Although there is no built-in variable &quot;A_LoopDelimiter&quot;, the example at the very bottom of this page demonstrates how to detect which delimiter was encountered for each field.</p>
<p>There is no restriction on the size of <em>InputVar</em> or its fields. In addition, if <em>InputVar</em>'s contents change during the execution of the loop, the loop will not &quot;see&quot; the changes because it is operating on a temporary copy of the original contents.</p>
<p>To arrange the fields in a different order prior to parsing, use the <a href="Sort.htm">Sort</a> command.</p>
<p>See <a href="Loop.htm">Loop</a> for information about <a href="Block.htm">Blocks</a>, <a href="Break.htm">Break</a>, <a href="Continue.htm">Continue</a>, and the A_Index variable (which exists in every type of loop).</p>
<h2>Related</h2>
<p><a href="StringSplit.htm">StringSplit</a>, <a href="LoopReadFile.htm">file-reading loop</a>, <a href="Loop.htm">Loop</a>, <a href="Break.htm">Break</a>, <a href="Continue.htm">Continue</a>, <a href="Block.htm">Blocks</a>, <a href="Sort.htm">Sort</a>, <a href="FileSetAttrib.htm">FileSetAttrib</a>, <a href="FileSetTime.htm">FileSetTime</a></p>
<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>Colors := "red,green,blue"
Loop, parse, Colors, `,
{
    MsgBox, Color number %A_Index% is %A_LoopField%.
}</pre>
</div>

<div class="ex" id="ExFileRead">
<p><a href="#ExFileRead">#2</a>: Read the lines inside a variable, one by one (similar to a <a href="LoopReadFile.htm">file-reading</a> loop). A file can be loaded into a variable via <a href="FileRead.htm">FileRead</a>:</p>
<pre>Loop, parse, FileContents, `n, `r  <em>; Specifying `n prior to `r allows both Windows and Unix files to be parsed.</em>
{
    MsgBox, 4, , Line number %A_Index% is %A_LoopField%.`n`nContinue?
    IfMsgBox, No, break
}</pre>
</div>

<div class="ex" id="ExClipboard">
<p><a href="#ExClipboard">#3</a>: This is the same as the example above except that it's for the clipboard. It's useful whenever the clipboard contains files, such as those copied from an open Explorer window (the program automatically converts such files to their file names):</p>
<pre>Loop, parse, clipboard, `n, `r
{
    MsgBox, 4, , File number %A_Index% is %A_LoopField%.`n`nContinue?
    IfMsgBox, No, break
}</pre>
</div>

<div class="ex" id="ExCSV">
<p><a href="#ExCSV">#4</a>: Parse a comma separated value (CSV) file:</p>
<pre>Loop, read, C:\Database Export.csv
{
    LineNumber := A_Index
    Loop, parse, A_LoopReadLine, CSV
    {
        MsgBox, 4, , Field %LineNumber%-%A_Index% is:`n%A_LoopField%`n`nContinue?
        IfMsgBox, No
            return
    }
}</pre>
</div>

<div class="ex" id="ExDelimiter">
<p><a href="#ExDelimiter">#5</a>: Determining which delimiter was encountered.</p>
<pre><em>; Initialize string to search.</em>
Colors := "red,green|blue;yellow|cyan,magenta"
<em>; Initialize counter to keep track of our position in the string.</em>
Position := 0

Loop, Parse, Colors, `,|;
{
    <em>; Calculate the position of the delimiter at the end of this field.</em>
    Position += StrLen(A_LoopField) + 1
    <em>; Retrieve the delimiter found by the parsing loop.</em>
    Delimiter := SubStr(Colors, Position, 1)

    MsgBox Field: %A_LoopField%`nDelimiter: %Delimiter%
}</pre>
</div>

</body>
</html>
